JavaScript API
Соединение с сервером
Функция start принимает настройки соединения и открывает соединение. Здесь opt это объект с опциями подключения.
cometApi.start({dev_id:15, user_id:1, user_key:"userHash", node:"app.comet-server.ru"})
- dev_id обязательный параметр это публичный ключ разработчика.
- user_id не обязательный параметр, это идентификатор пользователя нужен для авторизации пользователя на комет сервере
- user_key не обязательный параметр, это хеш авторизации пользователя нужен для авторизации пользователя на комет сервере
- node - если вы разворачиваете CppComet на своём сервере, то надо указать адрес вашего сервера ( Если комет сервер работает не на 80 порту то обязательно надо указать порт например так node:"app.comet-server.ru:8087" )
Для переподключения к серверу используйте функцию restart
cometApi.restart({dev_id:15, user_id:1, user_key:"userHash"})
При переподключении вы можете переопределить параметры подключения или оставить их прежними.
Подписка на получение сообщений из канала
Функция subscription добавляет подписки на каналы, события в каналах и отчёты о доставке сообщений в каналы. Для подписки на сообщения в канале:
cometApi.subscription("имя_канала", function(data){ console.log(data) } )
- Первый аргумент - имя канала должно быть короче 32 символов и должно состоять из символов A-Za-z0-9 и символа минус и знака подчёркивания.
- Второй аргумент - callback функция которая будет вызвана при получении сообщения из этого канала.
Обратите внимание что телом сообщения может быть json строка. Если это так то она автоматически будет преобразована в объект.
cometApi.subscription( "pipe_name.event_name", function(e){ console.log(["event", e])})
Подписка на канал "Имя_канала"
cometApi.subscription("Имя_канала", function(e){ console.log(e)})
Подписка на канал событие "имя_события" в канале "Имя_канала"
cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})
Подписка на отчёт о доставке в канал "Имя_канала"
cometApi.subscription("#Имя_канала", function(e){ console.log(e)})
Подписка на все входящие сообщения из всех каналов на которые подписан этот клиент
cometApi.subscription(function(e){ console.log(e)})
Пример с online demo как принять сообщение из канала в JavaScript?
Отписка от получения сообщений из канала
Функция subscription возвращает строку subscription_id которая нам может понадобится если мы захотим отписать функцию от получения сообщений.
var subscriptionId = cometApi.subscription("Имя_канала.имя_события", function(e){ console.log(e)})
Для отписки от получения сообщений вызовите
cometApi.unsubscription(subscriptionId)
Зарезервированные имена каналов
Основная статья зарезервированные имена каналов
Не рекомендуется использовать в своих проектах имена каналов вида "bin_", "big_", "push_", "comet_", "self_", "trust_" и "sys_*" эти имена возможно будут использованы для дальнейшего расширения функционала. И будут иметь какие ни будь не обычные свойства по сравнению с другими именами каналов.
Так же есть каналы с особыми свойствами, о всех них ниже по тексту. * msg - Для доставки личных сообщений в соответствии с данными авторизации * user_status_ - для автоматического уведомления JS api о статусе пользователей * web_ - Каналы в которые можно отправлять сообщения как из CometQL так и из JS api * track_* - для автоматического уведомления JS api о том что кто то подписался или отписался от этого канала
Подписка на получение личных сообщений ( канал msg )======
Подписка на сообщения от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя)
cometApi.subscription("msg", function(e){ console.log(e)})
Подписка на сообщения с именем события "имя_события" от сервера доставленные в соответствии с данными авторизации (то есть по id пользователя)
cometApi.subscription("msg.имя_события", function(e){ console.log(e)})
Более подробно про механизм авторизации на комет сервере и про личные сообщения смотрите в статье Авторизация пользователей на комет сервере
Подписка на изменение статуса пользователя ( каналы user_status_* )======
Есть возможность из JS подписаться на уведомления о том когда определённый пользователь авторизуется на комет сервере или на оборот отключится от него.
Когда пользователь на комет сервере авторизуется то комет сервер автоматически отправляет сигнал в канал user_status_{идентификатор пользователя} с именем события online. А когда авторизованный пользователь уходит в offline то комет сервер тоже генерирует событие.
// Подписываемся на уведомление о том что пользователь с id=12 online
cometApi.subscription("user_status_12.online", function(event)
{
console.log("Пользователь с id=12 online")
})
// Подписываемся на уведомление о том что пользователь с id=12 offline
cometApi.subscription("user_status_12.offline", function(event)
{
console.log("Пользователь с id=12 offline")
})
Список пользователей онлайн ( каналы track_* )======
Каналы с именем вида track_* автоматически генерируют события subscription и unsubscription внутри себя каждый раз как кто то подписывается или отписывается от этого канала
cometApi.subscription("track_online.subscription", function(msg)
{
// Обработка события что кто то зашёл на сайт и подписался на канал track_online
});
cometApi.subscription("track_online.unsubscription", function(msg)
{
// Обработка события что кто то покинул сайт и/или отписался от канала track_online
});
Этот вид каналов создан специально для облегчения создания динамически обновляемых списков пользователей онлайн. Основная статья список пользователей онлайн
Отправка сообщений в канал из JS (каналы web_*)
Функция web_pipe_send позволяет из JavaScript отправлять сообщения в канал минуя ваш сервер, то есть напрямую обращаясь к comet серверу. Это позволяет пересылать сообщения между клиентами вообще не загружая ваш сервер. Так же благодаря обращению на прямую к comet серверу время доставки сообщения от клиента к клиенту минимально.
Отправлять сообщения в канал из JavaScript можно только если имя канала начинается с web_ в то время как для CometQL такого ограничения нет.
cometApi.web_pipe_send("web_pipe_name", "event_name", "message")
Для того чтобы получить отчёт о доставке сообщения в канал "Имя_канала" используйте subscription
cometApi.subscription("#Имя_канала", function(e){ console.log(e)})
Так как комет сервер поддерживает авторизацию пользователей, он сам добавляет id пользователя к сообщению таким образом что пользователь отправивший сообщение не может отправить чужой id. Для отключения этой возможности надо добавить символ "@" перед именем канала в который отправляется сообщение. В таком случаи доставленное сообщение будет выглядеть так как будто его отправил не авторизованный пользователь.
cometApi.web_pipe_send("@web_pipe_name", "event_name", "message")
Пример чата на основе отправки сообщений из JavaScript Api прямо в комет сервер
Формат входящих сообщений
data: {} // Сообщение пользователя
server_info:
event: "undefined" // Имя события
history: false // Если true то это данные загружаемые из истории канала а не пришедшие сейчас
marker: undefined // Специальный идентификатор, определён только когда history равно true
pipe: "web_chat_pipe" // Имя канала которому адресовано сообщение
user_id: 0 // Id отправителя, если 0 то не задан. Будет добавляется автоматически если человек отправивший сообщение в канал авторизован на комет сервере.
Поле server_info.user_id в приходящем сообщении заполняется чем то кроме нуля только если сообщение отправлено в канал из JavaScript API и при этом отправитель прошёл авторизацию на комет сервере. Оно содержит user_id отправителя.
Получение последних сообщений из канала
В комет сервере есть возможность для некоторых каналов включить механизм запоминания последних N сообщений через них.
Логирование проходящих сообщений можно включить запросом CometQL к таблице pipes_settings.
Если функция логирования включена то вызов метода get_pipe_log инициирует отправку всех сообщений из истории в канале на клиент.
cometApi.get_pipe_log("web_pipe_name")
Сообщения пришедшие из истории канала будут иметь свойство history=true
Получение количества подписчиков в канале
Функция count_users_in_pipe даёт возможность узнать количество подписчиков в канале.
У функции count_users_in_pipe первый аргумент это имя канала а вторым аргументом передаётся callback функция в которую будет передан ответ.
cometApi.count_users_in_pipe("web_chat_pipe", function(res)
{
console.log("count_users_in_pipe", res, res.data.user_in_pipe)
})
Но в отличии от CometQL запроса эта функция может показывать количество подписчиков только в тех каналах у которых имя начинается с web_ к примеру для канала web_chat_pipe она сработает а для канала chat_pipe не сработает. Это ограничение введено для того что бы была возможность создать такой канал в котором количество подписчиков не сможет узнать кто попало через js api
Определение статуса авторизации на комет сервере
Основная статья авторизация на комет сервере
У комет сервера есть возможность авторизации пользователей. Авторизация может быть полезна для того что бы была возможность определить кто именно отправил сообщение в канал или для адресной отправки сообщений пользователям.
Из JavaScript api вы можете отслеживать изменение статуса авторизации на комет сервере.
// Добавление callBack функции на уведомление об успешной авторизации
cometApi.onAuthSuccess(function(){
console.log("Подключились и авторизовались успешно")
})
// Добавление callBack функции на уведомление об не успешной авторизации
cometApi.onAuthFalill(function(){
console.log("Подключились успешно но не авторизовались")
})
Эти функции будут вызваны в момент смены статуса авторизации. То есть как минимум один раз при подключении к комет серверу и при каждой смене статуса если в момент работы скрипта авторизация пропадёт или на оборот произойдёт.
Так же в любой момент времени можно вызвать функцию isAuthorized для определения статуса авторизации.
cometApi.isAuthorized()
Функция isAuthorized может вернуть 3 разных значения * false - авторизация не пройдена * true - авторизация пройдена * undefined - статус ещё не определён, этот ответ возвращается ещё до попытки подключения к комет серверу
Определение мастер вкладки
В JavaScript API есть функция которая из нескольких открытых вкладок назначает одну вкладку "главной" она называется мастер вкладкой, а все остальные вкладки определяются как salve вкладки. Функция isMaster возвращает true если выполняется в контексте мастер вкладки и false если выполняется в контексте salave вкладки.
cometApi.isMaster()
Определение какая вкладка является мастер вкладкой, а какая slave может быть полезно если вам надо сделать определённое действие только на одной вкладке а не во всех. Например у вас чат открыт на 3 страницах и при каждом входящем сообщении воспроизводится звуковое уведомление. В таком примере будет правильно если только одна вкладка будет воспроизводить звук а не все 3.
Больше подробностей про взаимодействие между вкладками смотрите в статье обмен сообщениями между вкладками браузера.
Примечание
В ряде примеров файл CometServerApi.js вставляется следующим образом:
<script src="//comet-server.ru/CometServerApi.js" type="text/javascript"></script>
Такой подход допустим только для тестов и в период разработки. Но не для постоянного использования. Так как по адресу [[http://comet-server.ru/CometServerApi.js]] расположена последняя на данный момент версия JavaScript Api и через некоторое время когда выйдет следующая версия JavaScript Api может случится так что она не будет иметь полную обратную совместимость с той версией которую использовали вы в период разработки. И ваше приложение может из за этого начать работать не верно или просто сломается.
Для предотвращения такой ситуации надо просто 1 раз скачать файл CometServerApi.js на свой сервер и потом использовать именно его до тех пор пока вам не понадобится обновить CometServerApi.js
Дополнительная информация
- Зарезервированные имена каналов
- CometQL API
- Почему скрипт работает на локальной машине и не работает на хостинге?
- Что такое и зачем нужен "Публичный идентификатор разработчика" и "Секретный ключ разработчика"?
- Как отправить сообщение в произвольный канал и как его потом получить на другой странице?
- Как реализовать механизм отслеживания вхождения пользователей на сайт. То есть список посетителей обновляющийся на "лету"?
- Может ли кто то посторонний получать сообщение из каналов